home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / ufexpand.zip / FEXPAND.ZIP / FEXPAND.DOC < prev    next >
Text File  |  1993-03-22  |  9KB  |  266 lines
  1.  
  2.                         FILE TEMPLATE EXPANDER
  3.                    A Shareware 'C' Utility Library
  4.  
  5.                                 from
  6.  
  7.                              Joe Acunzo
  8.                           10 Conifer Drive
  9.                          Branford, CT  06405
  10.  
  11.  
  12. 1. WHAT IS IT ANYWAY?
  13.  
  14. 2. INSTALLATION
  15.  
  16. 3. WILDCARDING CHARACTERS
  17.  
  18. 4. EXAMPLES
  19.  
  20. 5. SORTING
  21.  
  22. 6. 'C' FUNCTIONS
  23.  
  24. 7. COMPILERS SUPPORTED
  25.  
  26. 8. AUTOMATIC COMMAND LINE EXPANSION
  27.  
  28. 9. REGISTERING
  29.  
  30.  
  31.  
  32. 1. WHAT IS IT ANYWAY?
  33.  
  34. The File Template Expander (FTE) is a shareware library of 'C'
  35. callable function to expand wildcard characters in filenames (i.e.
  36. "file templates").  It is a more powerful expander than those
  37. provided with most 'C' runtime libraries (i.e. Microsofts
  38. "setargv").  Most 'C' runtime libraries only support wildcarding of
  39. file names using the standard '*' and '?' characters (multiple and
  40. single character matches respectively).  Besides this support, FTE
  41. also allows for wildcarding of directories names (0-N levels deep), a
  42. "not" templating ability, and putting file templates into a file. 
  43. There is also the abililty to pass a string containing one or more
  44. file templates and have that expanded as well.
  45.  
  46. In summary, FTE supports:
  47.  
  48.     o  0-N characters matching (using '*')
  49.     o  1 character matching (using '?')
  50.     o  directory name matching
  51.     o  any level of directories deep
  52.     o  not template ability
  53.     o  file templates in a file
  54.         o  file templates in a string
  55.         o  sorts matches
  56.         o  setargv replacement
  57.  
  58.  
  59. 2. INSTALLATION
  60.  
  61. FTE is distributed as a ZIP file.  It should be unzipped with the -d
  62. switch which automatically creates subdirectories that are stored in
  63. the ZIP file.  
  64.  
  65.  
  66. 3. WILDCARDING CHARACTERS
  67.  
  68. Besides the astericks ('*') and question mark ('?'), FTE also
  69. considers the pound sign ('#'), commercial at sign ('@'), and
  70. apostrophe (') specially.  Here is summary of these characters:
  71.  
  72.     *            match 0 or more characters
  73.     ?            match exactly one character
  74.     #            match 0 or more directories
  75.     !<template>  don't match <template>
  76.     @<filename>  <filename> contains additional templates.
  77.     '....'       any string enclosed in single quotes is not expanded
  78.  
  79.  
  80. 4. EXAMPLES
  81.  
  82. Some examples will help illustrate the power of FTE.  To the left are
  83. file templates and to the right are files that would match:
  84.  
  85. File Template          Possible Matches
  86. --------------------------------------------------
  87.     *.c                a.c
  88.                        b.c
  89.  
  90.     a?.c               a1.c
  91.                        a2.c
  92.  
  93.     \rd\fexp*\*.c     \rd\fexp\a.c
  94.                       \rd\fexpand\a.c
  95.  
  96.     \rd\fexp*\#\*.c    \rd\fexp\a.c
  97.                        \rd\fexpand\a.c
  98.                        \rd\fexpnew\a.c
  99.                        \rd\fexp\src\a.c
  100.                        \rd\fexpand\src\old\a.c
  101.  
  102.     \#\*.*             <matches ALL files on the current drive>
  103.  
  104.     D:\#\help.exe      <matches ALL help.exe files on the D: drive>
  105.  
  106.     '\rd\f*\a.c'       \rd\f*\a.c  <single quotes prevents expansion>
  107.  
  108. If the file FILE.LST contained these three lines:
  109.  
  110.     *.C *.H
  111.     MAKEFILE
  112.     *.DOC
  113.  
  114. then the following would match:
  115.  
  116.     @file.lst          a.c
  117.                        b.c
  118.                        exp.doc
  119.                        makefile
  120.                        z.h
  121.  
  122. If there where three files as follows: X1.C, X2.C, and Y.C then:
  123.  
  124.      *.c !x*.c         y.c
  125.  
  126. For some coding examples of using the File Template Expander see the
  127. files example1.c and example2.c (mscbuild.bat compiles/links these
  128. examples for Microsoft C and bccbuild compiles/links them for Borland C).
  129.  
  130.  
  131. 5. SORTING
  132.  
  133. All files that match a specified template are sorted, but not merged
  134. across templates.  For example:
  135.  
  136.      *.c *.h
  137.  
  138. would result in all C files sorted and then all H files sorted separately.
  139.  
  140. If the desired result is to sort across all templates (that is, merge
  141. all sorts), then the "merge flag" must be set to TRUE.  Duplicate
  142. file expansions are ignored.  For example, abc.c and *.c would yield
  143. only one abc.c.
  144.  
  145. With the merge option, ALL arguments are sorted in.  This may not be
  146. the desired result if an argument given is not a file name since it
  147. will be sorted in with all of the matching file names.  For example,
  148. if you would like to expand the following command line:
  149.  
  150.     /C *.c /H *.h
  151.  
  152. and you had the "merge flag" set to TRUE, then the /C and the /H
  153. switches would be sorted in with all of the matches for *.c and *.h.
  154.  
  155.  
  156. 6. 'C' FUNCTIONS
  157.  
  158. This section lists the callable 'C' functions in the library.
  159. Fexpand.h contains prototypes for the functions listed here.
  160.  
  161. NOTE: If you would rather have the command line expanded before main()
  162. is ever called, see section 8.AUTOMATIC COMMAND LINE EXPANSION.
  163.  
  164.  
  165. FUNCTIONS:
  166.  
  167. char **FileTemplateExpand(
  168.     int count, char *templates[],
  169.     int ignore_first, int merge_all, int *new_count);
  170.  
  171. char **FileTemplateExpandString(
  172.     char *string,
  173.     int ignore_first, int merge_all, int *new_count);
  174.  
  175. char **FileTemplateExpandFilter(
  176.     int (*filter)(char *),
  177.     int count, char *templates[], int ignore_first,
  178.     int merge_all, int *new_count);
  179.  
  180. char **FileTemplateExpandFilterString(
  181.     int (*filter)(char *),
  182.     char *string,
  183.     int ignore_first, int merge_all, int *new_count);
  184.  
  185.  
  186. PASSED ARGUMENTS:
  187.  
  188. count             Number of elements in the 'templates' array.
  189.  
  190. templates         An array of pointers to strings that may (or may not)
  191.                       contain file templates to be expanded.
  192.  
  193. int ignore_first  If TRUE, don't try and expand file_templates[0].
  194.                       Just put in into the new template array at position 0.
  195.                       (Usefull if you are passing argv where argv[0]
  196.                        is the program name and not an argument to expand.)
  197.  
  198. int merge_all     If TRUE, then matches to all templates are sorted together.
  199.  
  200. string            A string containing space and tab delimited file templates.
  201.                       Double quotes may be used to embed white space.
  202.                       (For example, A "B C" D are four arguments.)
  203.  
  204. filter            A pointer to a function that is called with every match.
  205.                   It is passed the full path to the matching file name.
  206.                   If it returns TRUE, the file is included.  If it returns
  207.                   FALSE, the file is discarded.
  208.  
  209.  
  210. RETURNED ARGUMENTS:
  211.  
  212. int new_count     Count of pointers in the returned array of pointers.
  213.  
  214. <return>          Pointer to an array of pointers that contain the expansion.
  215.  
  216. The returned array of pointers and everything it points at is
  217. allocated on the running programs heap (using malloc).  When no
  218. longer needed it can be freed up using the standard free() function.
  219.  
  220. As you can see from the functions above, there are basically two ways
  221. to call it - with an array of pointers and a count (ala argc/argv) or
  222. with a string.  Then, you can decide if you would like a "filter"
  223. function which can "weed out" unwanted files.
  224.  
  225. For some coding examples of using the File Template Expander see the
  226. files example1.c and example2.c (mscbuild.bat compiles/links these
  227. examples for Microsoft C and bccbuild compiles/links them for Borland C).
  228.  
  229.  
  230. 7. COMPILERS SUPPORTED
  231.  
  232. The Microsoft and Borland C compilers are supported.  There is a
  233. library for each of the small, compact, medium, and large models for
  234. each compiler as follows:
  235.  
  236.           Microsoft            Borland
  237.           ------------------------------------
  238. Small     msc\Sfexpand.lib     bcc\Sfexpand.lib
  239. Medium    msc\Mfexpand.lib     bcc\Mfexpand.lib
  240. Compact   msc\Cfexpand.lib     bcc\Cfexpand.lib
  241. Large     msc\Lfexpand.lib     bcc\Lfexpand.lib
  242.  
  243. Source code is available (which is in an ANSI standard format).  See
  244. the information about registering.
  245.  
  246.  
  247. 8. AUTOMATIC COMMAND LINE EXPANSION
  248.  
  249. For the Microsoft compiler/library, there is the ability to have the
  250. command line automatically expanded (i.e. argv[] is expanded before
  251. ever being passed to main().)  With FTE, this is possible by linking
  252. with the appropriate Xsetargv.obj module where 'X' is one of S, M, C,
  253. or L for Small, Medium, Compact, and Large model respectively.  The
  254. batch file src\mscbuild.bat gives an example of building such a
  255. program.
  256.  
  257.  
  258. 9. REGISTERING
  259.  
  260. FTE is shareware, and as such, should be registered if you intend to
  261. continue to use it.  For a description of the shareware concept, see
  262. the file SHARWAR.DOC.  By registering, you will receive the latest
  263. version and a version which does not have that annoying prompt that
  264. the unregistered version has.  Source code is also available.  To
  265. register, see the file REGISTER.DOC.
  266.